The Compression Parameters Structure4

Compressor components accept the parameters that govern a compression operation in the form of a data structure. This data structure is called a compression parameters structure . This structure is used by the CDBandCompress and CDPreCompress functions (described on CDBandCompress and CDPreCompress , respectively).

The compression parameters structure is defined by the CodecCompressParams data type as follows:

Field descriptions

sequenceID: Contains a unique sequence identifier. If the image to be compressed is part of a sequence, this field contains the sequence identifier that was assigned by the CompressSequenceBegin function. If the image is not part of a sequence, this field is set to 0.
imageDescription: Contains a handle to the image description structure that describes the image to be compressed.
data: Points to a location to receive the compressed image data. This is a 32-bit clean address--do not call StripAddress . If there is not sufficient memory to store the compressed image, the application may choose to write the compressed data to mass storage during the compression operation. The flushProc field identifies the data-unloading function that the application provides for this purpose.; This field is used only by the CDBandCompress function.
bufferSize: Contains the size of the buffer specified by the data field. Your component sets the value of the bufferSize field to the number of bytes of compressed data written into the buffer. Your component should not return more data than the buffer can hold--it should return a nonzero result code instead.; This field is used only by the CDBandCompress function.
frameNumber: Contains a frame identifier. Indicates the relative frame number within the sequence. The Image Compression Manager increments this value for each frame in the sequence.; This field is used only by the CDBandCompress function.
startLine: Contains the starting line for the band. This field indicates the starting line number for the band to be compressed. The line number refers to the pixel row in the image, starting from the top of the image. The first row is row number 0.; This field is used only by the CDBandCompress function.
stopLine: Contains the ending line for the band. This field indicates the ending line number for the band to be compressed. The line number refers to the pixel row in the image, starting from the top of the image. The first row in the image is row number 0.; The image band includes the row specified by this field. So, to define a band that contains one row of pixels at the top of an image, you set the startLine field to 0 and the stopLine field to 1.
conditionFlags: Contains flags that identify the condition under which your component has been called. This field is used only by the CDBandCompress function. In addition, these fields contain information about actions taken by your component. Condition flags fields contain the following flags:



 
                  #define codecConditionFirstBand                   (1L<<0)         

                  #define codecConditionLastBand                    (1L<<1)

The codecConditionFirstBand constant is an input flag that indicates if this is the first band in the frame. If this flag is set to 1, then your component is being called for the first time for the current frame.; The codecConditionLastBand constant is an input flag that indicates if this is the last band in the frame. If this flag is set to 1, then your component is being called for the last time for the current frame. If the codecConditionFirstBand flag is also set to 1, this is the only time the Image Compression Manager is calling your component for the current frame.; The codecConditionCodecChangedMask constant is an output flag that indicates that the component has changed the mask bits. If your image decompressor component can mask decompressed images and if some of the image pixels should not be written to the screen, set to 0 the corresponding bits in the mask defined by the maskBits field in the decompression parameter structure. In addition, set this flag to 1. Otherwise, set this flag to 0.
callerFlags: The callerFlags constant is an output flag that contains flags providing further control information. See the chapter "Image Compression Manager" in Inside Macintosh: QuickTime for information about the Image Compression Manager function control flags. The following flags are available:
capabilities: Points to a compressor capability structure. The Image Compression Manager uses this field to determine the capabilities of your compressor component.; This field is used only by the CDPreCompress function (described on CDPreCompress ).
progressProcRecord: Contains a progress function structure. During the compression operation, your compressor may occasionally call a function that the application provides in order to report your progress (see the chapter "Image Compression Manager" in Inside Macintosh: QuickTime for more information about progress functions). This field contains a structure that identifies the progress function. If the progressProc field in this structure is set to nil , the application has not supplied a progress function.; This structure is used only by the CDBandCompress function (described on CDBandCompress ).
completionProcRecord: Contains a completion function structure. This structure governs whether you perform the compression asynchronously. If the completionProc field in this structure is set to nil , perform the compression synchronously. If this field is not nil , it specifies an application completion function. Perform the compression asynchronously and call that completion function when your component is finished. See the chapter "Image Compression Manager" in Inside Macintosh: QuickTime for information on calling completion functions. If the completionProc field in this structure has a value of -1, perform the operation asynchronously but do not call the application's completion function.; This structure is used only by the CDBandCompress function.
flushProcRecord: Contains a data-unloading function structure. If there is not enough memory to store the compressed image, the application may provide a function that unloads some of the compressed data (see the chapter "Image Compression Manager" in Inside Macintosh: QuickTime for more information about data-unloading functions). This field contains a structure that identifies that data-unloading function.; If the application did not provide a data-unloading function, the flushProc field in this structure is set to nil . In this case, your component writes the entire compressed image into the memory location specified by the data field.; The data-unloading function structure is defined by the flushProcRecord data type as follows:



 
                    struct FlushProcRecord {

                        FlushProcPtr flushProc; /* pointer to 

                                                            data-unloading

                                                            function */

                        long flushRefCon;            /* data-unloading

                                                            function reference

                                                            constant */

                    };

                    typedef struct FlushProcRecord FlushProcRecord;

                    typedef FlushProcRecord *FlushProcRecordPtr;

The data-unloading function structure is used only by the CDBandCompress function (described on CDBandCompress ).
srcPixMap: Points to the image to be compressed. The image must be stored in a pixel map structure. The contents of this pixel map differ from a standard pixel map in two ways. First, the rowBytes field is a full 16-bit value--the high-order bit is not necessarily set to 1. Second, the baseAddr field must contain a 32-bit clean address.; This field is used only by the CDBandCompress function.
prevPixMap: Points to a pixel map containing the previous image. If the image to be compressed is part of a sequence that is being temporally compressed, this field defines the previous image for temporal compression. Your component should then use this previous image as the basis of comparison for the image to be compressed.; If the temporalQuality field is set to 0, do not perform temporal compression. If the codecFlagUpdatePrevious flag or the codecFlagUpdatePreviousComp flag in the flags field is set to 1, update the previous image at the end of the compression operation.; The contents of this pixel map differ from a standard pixel map in two ways. First, the rowBytes field is a full 16-bit value--the high-order bit is not necessarily set to 1. Second, the baseAddr field must contain a 32-bit clean address.; This field is used only by the CDBandCompress function.
spatialQuality: Specifies the desired compressed image quality. See the chapter "Image Compression Manager" in Inside Macintosh: QuickTime for valid values.; This field is used only by the CDBandCompress function.; Check to see if the value of this parameter is nil and, if so, do not write to location 0.
temporalQuality: Specifies the desired sequence temporal quality. This field governs the level of compression the application desires with respect to information in successive frames in the sequence. If this field is set to 0, do not perform temporal compression on this frame. See the chapter "Image Compression Manger" in Inside Macintosh: QuickTime for other available values.; This field is used only by the CDBandCompress function (described on CDBandCompress ).; Check to see if the value of this parameter is nil and, if so, do not write to location 0.
similarity: Indicates the similarity between adjacent frames when performing temporal compression. Your component returns a fixed-point number in this field. That value indicates the relative similarity between the frame just compressed and the previous frame. Valid values range from 0 (key frame) to 1 (identical).; This field is used only by the CDBandCompress function.; Check to see if the value of this parameter is nil and, if so, do not write to location 0.
dataRateParams: Points to the parameters used when performing data rate constraint.
reserved: Reserved for use by Apple.